IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/u_man/cat1/rpcgen.z/rpcgen

Text File | 1998-10-20 | 17KB | 331 lines

rrrrppppccccggggeeeennnn((((1111))))                                                            rrrrppppccccggggeeeennnn((((1111))))



NNNNAAAAMMMMEEEE
     _rrrr_pppp_cccc_gggg_eeee_nnnn - an RPC protocol compiler

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _rrrr_pppp_cccc_gggg_eeee_nnnn _i_n_f_i_l_e
     _rrrr_pppp_cccc_gggg_eeee_nnnn _[[[[_----_CCCC _c_p_p_c_m_d_]]]] _[[[[_----_DDDD_n_a_m_e_[[[[_====_v_a_l_u_e_]]]]_]]]] _[[[[_----_TTTT_]]]] _[[[[_----_PPPP_]]]] _[[[[_----_IIII _|||| _----_KKKK _s_e_c_s_]]]] _i_n_f_i_l_e
     _rrrr_pppp_cccc_gggg_eeee_nnnn _----_cccc_||||_----_hhhh_||||_----_llll_||||_----_mmmm_||||_----_tttt _[[[[_----_PPPP_]]]] _[[[[_----_oooo _o_u_t_f_i_l_e _]]]] _i_n_f_i_l_e
     _rrrr_pppp_cccc_gggg_eeee_nnnn _----_ssss _n_e_t_t_y_p_e _[[[[_----_oooo _o_u_t_f_i_l_e_]]]] _i_n_f_i_l_e
     _rrrr_pppp_cccc_gggg_eeee_nnnn _----_nnnn _n_e_t_i_d _[[[[_----_oooo _o_u_t_f_i_l_e_]]]] _i_n_f_i_l_e

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _rrrr_pppp_cccc_gggg_eeee_nnnn is a tool that generates C code to implement an RPC protocol.
     _rrrr_pppp_cccc_gggg_eeee_nnnn will produce file to be used with libc [see _iiii_nnnn_tttt_rrrr_oooo_...._3333_nnnn(1)].  To
     produce file to be used with libnsl see _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii(1).  The input to
     _rrrr_pppp_cccc_gggg_eeee_nnnn is a language similar to C known as RPC Language (Remote Procedure
     Call Language).

     _rrrr_pppp_cccc_gggg_eeee_nnnn is normally used as in the first synopsis where it takes an input
     file and generates up to four output files.  If the _i_n_f_i_l_e is named
     _pppp_rrrr_oooo_tttt_oooo_...._xxxx, then _rrrr_pppp_cccc_gggg_eeee_nnnn will generate a header file in _pppp_rrrr_oooo_tttt_oooo_...._hhhh, XDR routines
     in _pppp_rrrr_oooo_tttt_oooo______xxxx_dddd_rrrr_...._cccc, server-side stubs in _pppp_rrrr_oooo_tttt_oooo______ssss_vvvv_cccc_...._cccc, and client-side stubs
     in _pppp_rrrr_oooo_tttt_oooo______cccc_llll_nnnn_tttt_...._cccc.  With the _----_TTTT option, it will also generate the RPC
     dispatch table in _pppp_rrrr_oooo_tttt_oooo______tttt_bbbb_llll_...._iiii.

     The server created can be started both by the port monitors (for example,
     _iiii_nnnn_eeee_tttt_dddd or _llll_iiii_ssss_tttt_eeee_nnnn) or by itself.  When it is started by a port monitor, it
     creates servers only for the transport for which the file descriptor _0000
     was passed.  The name of the transport must be specified by setting up
     the environment variable _PPPP_MMMM______TTTT_RRRR_AAAA_NNNN_SSSS_PPPP_OOOO_RRRR_TTTT.  When the server generated by
     _rrrr_pppp_cccc_gggg_eeee_nnnn is executed, it creates server handles for all the transports
     specified in _NNNN_EEEE_TTTT_PPPP_AAAA_TTTT_HHHH environment variable, or if it is not set, it
     creates server handles for all the visible transports from _////_eeee_tttt_cccc_////_nnnn_eeee_tttt_cccc_oooo_nnnn_ffff_iiii_gggg
     file.  Note:  the transports are chosen at run time and not at compile
     time.  When the server is self-started, it backgrounds itself by default.
     A special symbol, _RRRR_PPPP_CCCC______SSSS_VVVV_CCCC______FFFF_GGGG, can be defined at compilation time to make
     the server process run in foreground.

     The second synopsis provides special features which allow for the
     creation of more sophisticated RPC servers.  These features include
     support for user provided _####_dddd_eeee_ffff_iiii_nnnn_eeee_ssss and RPC dispatch tables.  The entries
     in the RPC dispatch table contain:
          +o  pointers to the service routine corresponding to that procedure,
          +o  a pointer to the input and output arguments
          +o  the size of these routines
     A server can use the dispatch table to check authorization and then to
     execute the service routine; a client library may use it to deal with the
     details of storage management and XDR data conversion.

     The other three synopses shown above are used when one does not want to
     generate all the output files, but only a particular one.  Some examples
     of their usage is described in the EXAMPLE section below.  When _rrrr_pppp_cccc_gggg_eeee_nnnn is
     executed with the _----_ssss option, it creates servers for that particular class



                                                                        PPPPaaaaggggeeee 1111






rrrrppppccccggggeeeennnn((((1111))))                                                            rrrrppppccccggggeeeennnn((((1111))))



     of transports.  When executed with the _----_nnnn option, it creates a server for
     the transport specified by _n_e_t_i_d.  If _i_n_f_i_l_e is not specified, _rrrr_pppp_cccc_gggg_eeee_nnnn
     accepts the standard input.

     The C preprocessor, _cccc_cccc _----_EEEE [see _cccc_cccc(1)], is run on the input file before it
     is actually interpreted by _rrrr_pppp_cccc_gggg_eeee_nnnn.  For each type of output file, _rrrr_pppp_cccc_gggg_eeee_nnnn
     defines a special preprocessor symbol for use by the _rrrr_pppp_cccc_gggg_eeee_nnnn programmer:

     _RRRR_PPPP_CCCC______HHHH_DDDD_RRRR     defined when compiling into header files
     _RRRR_PPPP_CCCC______XXXX_DDDD_RRRR     defined when compiling into XDR routines
     _RRRR_PPPP_CCCC______SSSS_VVVV_CCCC     defined when compiling into server-side stubs
     _RRRR_PPPP_CCCC______CCCC_LLLL_NNNN_TTTT    defined when compiling into client-side stubs
     _RRRR_PPPP_CCCC______TTTT_BBBB_LLLL     defined when compiling into RPC dispatch tables

     Any line beginning with `_%%%%' is passed directly into the output file,
     uninterpreted by _rrrr_pppp_cccc_gggg_eeee_nnnn.

     For every data type referred to in _i_n_f_i_l_e, _rrrr_pppp_cccc_gggg_eeee_nnnn assumes that there
     exists a routine with the string _xxxx_dddd_rrrr_____ prepended to the name of the data
     type.  If this routine does not exist in the RPC/XDR library, it must be
     provided.  Providing an undefined data type allows customization of XDR
     routines.

     The following options are available:

     _----_CCCC _c_p_p_c_m_d
          Run the preprocessor command, _c_p_p_c_m_d, instead of the default, cpp.

     _----_cccc   Compile into XDR routines.

     _----_DDDD_n_a_m_e_[[[[_====_v_a_l_u_e_]]]]
          Define a symbol _n_a_m_e.  Equivalent to the _####_dddd_eeee_ffff_iiii_nnnn_eeee directive in the
          source.  If no _v_a_l_u_e is given, _v_a_l_u_e is defined as _1111.  This option
          may be specified more than once.

     _----_hhhh   Compile into _CCCC data-definitions (a header file).  The _----_TTTT option can
          be used in conjunction to produce a header file which supports RPC
          dispatch tables.

     _----_IIII   Compile support for _iiii_nnnn_eeee_tttt_dddd(1M) in the server side stubs.  Such
          servers can be self-started or can be started by _iiii_nnnn_eeee_tttt_dddd.  When the
          server is self-started, it backgrounds itself by default.  A special
          define symbol _RRRR_PPPP_CCCC______SSSS_VVVV_CCCC______FFFF_GGGG can be used to run the server process in
          foreground, or the user may simply compile without the _----_IIII option.

          If there are no pending client requests, the _iiii_nnnn_eeee_tttt_dddd servers exit
          after 120 seconds (default).  The default can be changed with the _----_KKKK
          option.  All the error messages for _iiii_nnnn_eeee_tttt_dddd servers are always logged
          with _ssss_yyyy_ssss_llll_oooo_gggg(3).






                                                                        PPPPaaaaggggeeee 2222






rrrrppppccccggggeeeennnn((((1111))))                                                            rrrrppppccccggggeeeennnn((((1111))))



          Note:  this option is supported for backward compatibility only.  By
          default, _rrrr_pppp_cccc_gggg_eeee_nnnn generates servers that can be invoked through
          portmonitors.

     _----_KKKK _s_e_c_s
          By default, services created using _rrrr_pppp_cccc_gggg_eeee_nnnn wait _1111_2222_0000 seconds after
          servicing a request before exiting.  That interval can be changed
          using the _----_KKKK flag.  To create a server that exits immediately upon
          servicing a request, _----_KKKK _0000 can be used.  To create a server that
          never exits, the appropriate argument is _----_KKKK _----_1111.

          When monitoring for a server, some portmonitors, like _llll_iiii_ssss_tttt_eeee_nnnn(1M),
          _a_l_w_a_y_s spawn a new process in response to a service request.  If it
          is known that a server will be used with such a monitor, the server
          should exit immediately on completion.  For such servers, _rrrr_pppp_cccc_gggg_eeee_nnnn
          should be used with _----_KKKK _----_1111.

     _----_llll   Compile into client-side stubs.

     _----_mmmm   Compile into server-side stubs, but do not generate a main routine.
          This option is useful for doing callback-routines and for users who
          need to write their own main routine to do initialization.

     _----_nnnn _n_e_t_i_d
          Compile into server-side stubs for the transport specified by _n_e_t_i_d.
          There should be an entry for _n_e_t_i_d in the netconfig database.  This
          option may be specified more than once, so as to compile a server
          that serves multiple transports.

     _----_oooo _o_u_t_f_i_l_e
          Specify the name of the output file.  If none is specified, standard
          output is used (_----_cccc, _----_hhhh, _----_llll, _----_mmmm, _----_nnnn, _----_ssss and _----_tttt modes only).

     _----_PPPP   Generate prototyped XDR and stub function declarations and
          definitions suitable for ANSI C and C++. The prototypes for the
          client- and server-side stubs are different; their declarations in
          the generated header file are conditionally-compiled with the values
          _RPCGEN_CLNT or _RPCGEN_SVC.  If you write your own client or server
          code, you must define the appropriate value in your source files
          before including the generated header file. Using the example above,
          the file for client code should use:

               #define _RPCGEN_CLNT
               #include "proto.h"

          and the file for server code should use:

               #define _RPCGEN_SVC
               #include "proto.h"






                                                                        PPPPaaaaggggeeee 3333






rrrrppppccccggggeeeennnn((((1111))))                                                            rrrrppppccccggggeeeennnn((((1111))))



     _----_ssss _n_e_t_t_y_p_e
          Compile into server-side stubs for all the transports belonging to
          the class _n_e_t_t_y_p_e.  The supported classes are _nnnn_eeee_tttt_pppp_aaaa_tttt_hhhh, _vvvv_iiii_ssss_iiii_bbbb_llll_eeee,
          _cccc_iiii_rrrr_cccc_uuuu_iiii_tttt______nnnn, _cccc_iiii_rrrr_cccc_uuuu_iiii_tttt______vvvv, _dddd_aaaa_tttt_aaaa_gggg_rrrr_aaaa_mmmm______nnnn, _dddd_aaaa_tttt_aaaa_gggg_rrrr_aaaa_mmmm______vvvv, _tttt_cccc_pppp, and _uuuu_dddd_pppp [see
          _rrrr_pppp_cccc(3N) for the meanings associated with these classes].  This
          option may be specified more than once.  Note:  the transports are
          chosen at run time and not at compile time.

     _----_tttt   Compile into RPC dispatch table.

     _----_TTTT   Generate the code to support RPC dispatch tables.

     The options _----_cccc, _----_hhhh, _----_llll, _----_mmmm, _----_ssss and _----_tttt are used exclusively to generate a
     particular type of file, while the options _----_DDDD, _----_PPPP, and _----_TTTT are global and
     can be used with the other options.

NNNNOOOOTTTTEEEESSSS
     The RPC Language does not support nesting of structures.  As a work-
     around, structures can be declared at the top-level, and their name used
     inside other structures in order to achieve the same effect.

     Name clashes can occur when using program definitions, since the apparent
     scoping does not really apply.  Most of these can be avoided by giving
     unique names for programs, versions, procedures and types.

     The server code generated with _----_nnnn option refers to the transport
     indicated by _n_e_t_i_d and hence is very site specific.

EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     The following example:

          rpcgen -T prot.x

     generates all the five files:  _pppp_rrrr_oooo_tttt_...._hhhh, _pppp_rrrr_oooo_tttt______cccc_llll_nnnn_tttt_...._cccc, _pppp_rrrr_oooo_tttt______ssss_vvvv_cccc_...._cccc,
     _pppp_rrrr_oooo_tttt______xxxx_dddd_rrrr_...._cccc and _pppp_rrrr_oooo_tttt______tttt_bbbb_llll_...._iiii.

     The following example sends the C data-definitions (header file) to the
     standard output.

          rpcgen -h prot.x

     To send the test version of the _----_DDDD_TTTT_EEEE_SSSS_TTTT, server side stubs for all the
     transport belonging to the class _dddd_aaaa_tttt_aaaa_gggg_rrrr_aaaa_mmmm______nnnn to standard output, use:

          rpcgen -s datagram_n -DTEST prot.x

     To create the server side stubs for the transport indicated by _n_e_t_i_d _tttt_cccc_pppp,
     use:

          rpcgen -n tcp -o prot_svc.c prot.x





                                                                        PPPPaaaaggggeeee 4444






rrrrppppccccggggeeeennnn((((1111))))                                                            rrrrppppccccggggeeeennnn((((1111))))



SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _cccc_cccc(1), _rrrr_pppp_gggg_eeee_nnnn______tttt_llll_iiii(1)





















































                                                                        PPPPaaaaggggeeee 5555